package com.maiko.maikoaiagent.tools;

import cn.hutool.core.io.FileUtil;
import cn.hutool.http.HttpUtil;
import com.maiko.maikoaiagent.constant.FileConstant;
import org.springframework.ai.tool.annotation.Tool;
import org.springframework.ai.tool.annotation.ToolParam;

import java.io.File;

/**
 * ResourceDownloadTool 是一个资源下载工具类，
 * 通过给定的 URL 下载网络资源，并将其保存到指定文件名。
 *
 * 使用 Hutool 工具包中的 HttpUtil 和 FileUtil 来简化文件下载与目录创建操作。
 *
 * 示例用法：
 * ResourceDownloadTool tool = new ResourceDownloadTool();
 * tool.downloadResource("https://example.com/image.png", "logo.png");
 *
 * 注意事项：
 * - 默认下载保存路径为 {@code FileConstant.FILE_SAVE_DIR + "/download"}
 * - 若目标文件名包含非法字符，建议在调用前进行校验或清洗
 * - 网络请求过程可能较慢，建议在业务层加上异步处理或超时控制
 *
 * 依赖组件：
 * - Hutool 工具包（https://hutool.cn/）
 *
 * 安全建议：
 * - 可增加 URL 白名单校验，避免恶意下载攻击
 * - 可在下载前校验资源大小、MIME 类型
 *
 * @author Maiko7
 * @create 2025-07-09 15:15
 */
public class ResourceDownloadTool {

    /**
     * 根据提供的 URL 下载资源文件，并保存为指定文件名。
     *
     * @param url      要下载的资源的完整 URL 地址
     * @param fileName 下载后保存的文件名（如 test.pdf、image.jpg）
     * @return 下载结果提示信息：成功返回文件保存路径，失败返回错误信息
     */
    @Tool(description = "Download a resource from a given URL")
    public String downloadResource(
            @ToolParam(description = "URL of the resource to download") String url,
            @ToolParam(description = "Name of the file to save the downloaded resource") String fileName) {

        // 资源保存目录：在 FILE_SAVE_DIR 下创建 download 子目录
        String fileDir = FileConstant.FILE_SAVE_DIR + "/download";

        // 文件完整路径
        String filePath = fileDir + "/" + fileName;

        try {
            // 确保目标目录存在
            FileUtil.mkdir(fileDir);

            // 下载文件并保存到指定路径
            HttpUtil.downloadFile(url, new File(filePath));

            return "Resource downloaded successfully to: " + filePath;
        } catch (Exception e) {
            // 异常处理，返回错误信息
            return "Error downloading resource: " + e.getMessage();
        }
    }
}


